{accessrmd} is currently in development. If you discover bugs or improvements, please review the code of conduct and contribute on GitHub.
{accessrmd} is a package written to help improve the accessibility of Rmarkdown documents. The standard Rmarkdown outputs have HTML structural issues that result in problems for people using screen readers. The purpose of {accessrmd} is to help developers in writing accessible Rmarkdown documents and in converting a back catalogue of documents in need of accessibility amendments.
{accessrmd} is currently limited to html_output only. It is not available on CRAN yet, but this is the aim once the first release has been published.
To install the development version:
devtools::install_github("datasciencecampus/accessrmd")
To attach the package:
library(accessrmd)
The HTML structure of standard rmarkdown outputs are not AA WCAG2.1 standard. AA is the standard required by all UK government digital services. In order to present HTML checks, I will be enlisting the help of the excellent, open-source WAVE accessibility tool. It doesn’t catch everything required for AA-compliance, but it’s a great way to get started with an accessibility audit, including helpful explanations for newcomers to WCAG 2.1 compliance.
The below image shows the output of a WAVE check on the standard Rmarkdown html output. As you can see, there are a number of errors and warnings. Click the image for more detail.
Click the image to view the full check on wave.webaim.org, opens in new window.
By executing a few functions from the {accessrmd} package, the html format issues can be easily remedied, without the developer needing to write any HTML. Please observe the output of an Rmarkdown which has been adjusted by {accessrmd} functions (again, you can click for an interactive check):
Click the image to view the full check on wave.webaim.org, opens in new window.
In this section, I will be working with a test Rmarkdown document. It contains a simple ggplot chart and a test image. Click to see the test Rmarkdown output.
Click to see the WAVE check. Note the errors and warnings.
The issues are caused by the HTML structure and YAML settings. The YAML currently looks like this:
lines <- readLines("test.Rmd")
# Show only the YAML
message(paste(lines[1:6], collapse = "\n"))
---
title: "Test"
author: "Richard Leyshon"
date: "25/07/2021"
output: html_document
---
access_head()Reads an Rmd file, converting the YAML header to a format that is screen-reader friendly.
Most of the issues with the test Rmarkdown can be fixed with this single function. We just need to call it and specify a few parameters:
rmd_path is the relative path to the Rmarkdown.lan value will be used to set the HTML lang attribute value. I’ll specify “en” for English.inplace = FALSE (the default) will ensure the original Rmd doesn’t get overwritten.access_head(rmd_path = "test.rmd", lan = "en")
Setting html lan to en
access_head() created an accessrmd directory with an adjusted rmd.
list.files("accessrmd", full.names = TRUE)
[1] "accessrmd/corrected_images.html" "accessrmd/corrected_images.rmd" "accessrmd/images.html"
[4] "accessrmd/images.rmd" "accessrmd/test.html" "accessrmd/test.rmd"
Click to view the output HTML.
Click to view the WAVE report.
This function has resolved the following issues:
The remaining errors or warnings are related to the chart and image. We can also view the file lines to see how the file was modified.
lines <- readLines("accessrmd/test.rmd")
# Show only the head
message(paste(lines[1:7], collapse = "\n"))
<html lang="en">
<header>
<title>Test</title>
<h1 id="title toc-ignore">Test</h1>
<h2 class="header_h2s">RichardLeyshon</h2>
<h2 class="header_h2s">25/07/2021</h2>
</header>
access_img()Reads in an image and produces the HTML structure expected by web accessibility checkers such as WAVE. Also works as a wrapper around {ggplot2} charts.
This function can be used to resolve the remaining issues in the Rmarkdown. Inserting access_img() will resolve the chart issue, as it works with ggplot2::last_plot().
For images using markdown syntax, replacing the markdown with access_img() will ensure the image is renderred with the expected alt text value. This is important as markdown syntax  renders unreliably, causing issues with duplicated alt text warnings on WAVE.
# store the correct code lines as length 1 character vectors
# chart code specifying alt text
chart <- 'access_img(alt = "Plot of pressure vs temperature.")'
# test image code, specifying alt text and dimensions
img <- as.character(
'`r access_img(img = "../www/then-and-now-carole-hersee.jpeg",
alt = "BBC Test card then and now.", wid = 800, ht = 450)`')
# read in the rmd lines
lines <- readLines("accessrmd/images.rmd")
# Replace the blank line following ggplot code with access_img
lines[32] <- chart
# Replace the inaccessible markdown image with inline r code.
lines[37] <- img
# create a new file
file.create("accessrmd/corrected_images.rmd")
# write the modified lines
writeLines(lines, "accessrmd/corrected_images.rmd")
# render the markdown
rmarkdown::render("accessrmd/corrected_images.rmd")
processing file: corrected_images.rmd
img derived from disk.
output file: corrected_images.knit.md
Output created: corrected_images.html
Click to view the output html.
check_alt_len()In development.
detect_html_lang()In development.
find_all_alts()In development.
find_all_imgs()Not exported. Find any markdown or HTML syntax images within read lines. Check any lines for images and return the line numbers and values.
handle_rmd_path()Not exported. Helper function.Checks rmd_path exists and that the file type is as expected.
sus_alt()Suspicious alt text - checks if an image’s alt text is equal to alt attribute placeholder values, including ‘nbsp’, ‘spacer’ and the src attribute value (filename).
A continuous deployment workflow has been employed in the development of {accessrmd}, using GitHub Actions.
This workflow has allowed efficient adaptation of the package modules while ensuring the integrity of the outputs and conditional behaviours.
CD workflows for this package include:
An automated test suite analagous to the checks run by CRAN on package submission.
This suite of checks is something that I tend to execute as part of my development practice. However, setting automated checks on push to the remote ensures that human error is mitigated. Collaborators or developers wishing to install the development version of {accessrmd} can be informed of the current state of the repository and assured of the package’s functionality.
As can be seen from the screenshot below, the package is tested for compatibility with three different operating systems, Windows, MacOS and 2 flavours of Ubuntu.
Clicking on an item in the check manifest allows you to view the detailed check schedule. If any checks failed, you can consult the log to help pinpoint the error.
Codecov test coverage
I utilise Test-Driven Development when writing software in order to mitigate against misuse cases.
@tired_actor ##duet with @brock1137 no please no ##funny ##Welcome2021 ##2021 ##newyear ##firstpost ##viral ##fyp ##foryou ##foryoupage ##comedy ##crying ##2020 ##RareAesthetic
♬ The Square Hole - Brock
All jokes to the side, ensuring that your functions are safe is vital. This helps mitigate against poor documentation and misinterpretation.
Code coverage gives an indication of the percentage of code lines that are exercised when the test battery is run. However, I would advise caution in assuming that a high coverage equates to quality software. It tends to be very easy to write a suite of tests that result in high coverage. This does not mean that all necessary exception handling has been considered and tested.
Thorough and well-considered test conditions are excellent tools in assuring quality software. It also means that you can turn your failures into future successes - every bug you encounter can be converted to a meaningful test.
Below, you can view the test coverage workflow on pushing to the remote.
Automated linting using the {lintr} package with GitHub actions is used to help ensure code adheres to the tidyverse style guide. Code readability is important in assisting collaboration. Data Science Campus guidance is to apply the tidyverse style guide.
Perhaps more important than the adopted style is to ensure that code is conscientiously commented. Your colleagues and future self will value the effort taken in explaining your code.